home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 2 / MacMania 2.toast / Demo's / Tools&Utilities / Updaters / Symantec C++ 6.0.1 Update / Release Notes / SS Supplement next >
Encoding:
Text File  |  1993-09-14  |  18.4 KB  |  431 lines  |  [TEXT/KAHL]
  1. 12 August 1993
  2. Font: 9 point Monaco
  3.  
  4.  
  5. Using SourceServer from the Think Project Manager
  6. _________________________________________________
  7.  
  8. This document describes:
  9.  
  10.     - Changes made to the Think Project Manager's interface with SourceServer
  11.     - Commands for SourceServer's command-line interface
  12.     - Hints and techniques for working with SourceServer
  13.     
  14. This document supplements Chapter 25,"Using SourceServer", in the Think C/ Symantec C++
  15. User's Guide. Where text differs, or is contradictory  between the two, you should assume
  16. that the information in this document is the correct version.
  17.  
  18. In the discussion below, SourceServer databases, SourceServer projects, and
  19. projector databases are treated interchangeably. Also, TPM is the acronym for
  20. "Think Project Manager."
  21.  
  22.  
  23. Tips, Techniques, and Changes to the Interface
  24. _____________________________________________
  25.  
  26. Nested Projects (subdatabases):
  27.  
  28. The single most important thing to insure acceptable performance (in terms of
  29. response time) is to make use of nested projector databases. Projector
  30. databases can keep track of 200 files in a single database, but if you put this many 
  31. files in one database, you will find yourself waiting several minutes before the CheckOut 
  32. dialog appears. Other operations will be similarly frustrating because of the amount of 
  33. time they take to complete. Using fewer files per database becomes even more
  34. important if the database file is kept on a server, since access to a remote host
  35. will also reduce performance.
  36.  
  37. When you use nested projects, each database can contain a smaller subset of
  38. source files, and response time can be kept to respectable levels. How you group files
  39. is up to you; you might do it according to a functional relationship between
  40. files. If you were putting the Think Class Library under source control, for
  41. example, you might have separate databases for the dialog classes, text classes, 
  42. table classes, etc.
  43.  
  44. Creating nested projector databases is straightforward. When you create a new
  45. projector database with SourceServer, a folder is created with a projectorDB file
  46. inside of it. The folder's name is what you use to refer to the database (in the
  47. mount project dialog, for example). By nesting the folders created for each
  48. database, SourceServer will treat them as one nested project.
  49.  
  50. Using our TCL example again, the folder layout might look like this:
  51.  
  52.                            My SourcesDB
  53.         _________________________|____________________________
  54.         |                   |                 |               |
  55.     Table classesDB   Text classesDB   More classesDB   Core SourcesDB
  56.                                                               |
  57.                                                         Core HeadersDB
  58.  
  59. This chart doesn't represent the entire TCL, but it shows the idea of using nested
  60. projects. Setting up nested databases is time consuming, but is well worth the
  61. effort. Response time will be significantly better than with a single project 
  62. containing every source file and header file.
  63.  
  64.  
  65. Removing a File from Source Control:
  66.  
  67. Once a file is added to a SourceServer database, a 'CKID' resource is added to
  68. the file to store relevant project information. The 'CKID' resource will also
  69. prevent the file from being checked into a different database. If you want to remove any
  70. association a file has with SourceServer, you can use the OrphanFile command (see
  71. the command line description below). 
  72.  
  73. Note that once you orphan a file, there is no way to check the file back into its
  74. former project because it no longer belongs to that project. You can, however,
  75. use the TransferCkid commmand to remedy this by transfering a 'ckid' resource with the
  76. correct project information to this file.
  77.  
  78.  
  79. Named Revisions:
  80.  
  81. It's not uncommon for a programmer to always work on the same subset of files in a
  82. large project, or to work on a given set of files for an extended period of time.
  83. The "Name Revisions..." dialog provides an easy way for each person to define working 
  84. sets of source files. Setting up a Named Revision with 'Dynamic Revision' will let you 
  85. always choose the most current file in a revision tree. Once a revision has been named, 
  86. you canselect it in the CheckOut dialog, rather than specifying each file you want
  87. individually.
  88.  
  89. Named Revisions can also be set with the 'Static Revision' option. Revisions
  90. named this way will refer to the versions of each file that are current at the time the
  91. revision is named. A typical use for this is to have a named set for a frozen
  92. version of code, such as beta or final releases.
  93.  
  94.  
  95. Why Newer is better:
  96.  
  97. The "Newer" button in the CheckOut dialog has been modified from its original
  98. implementation. Here's how it works now:
  99.  
  100. When you click on the Newer button, the Project Manager will look at files in the
  101. "Checkout to:" directory. Files will be highlighted if their newest (non-branch)
  102. revision is NOT already in that directory. Files will not be highlighted if you
  103. have a branch checked out, since you would normally intend to keep a branch if
  104. you've already checked it out.
  105.  
  106. If you option-click the Newer button, files will be selected that do exist in
  107. the "Checkout to:" directory, if they are older than the current revision AND are
  108. checked out as read only. This is the same as using -update from the command
  109. line. The effect is that all Read Only files in the directory are overwritten
  110. with the latest version of the file.
  111.  
  112. If the "CheckOut to:" directory is set to "Default Directories", then the Newer
  113. button works in way similar to the descriptions above, except that the actions
  114. are on a (TPM) project- wide basis. That is, clicking on the Newer button selects 
  115. all files in your project that are not already somewhere in your TPM project's tree 
  116. or the system tree. Likewise, option clicking will select all
  117. read-only files from the project that are on disk already. Files which cannot be
  118. found, or are not part of the TPM project, are not selected.
  119.  
  120. When using the "Default Directories" as the Checkout directory, files will be
  121. checked out to the location in which they were last found. Any local copies of
  122. files may be moved around freely in the project or system tree, and the file will
  123. be checked out properly. If a file isn't in the same tree as where it was last
  124. found, CheckOut will put the file in your project's top level directory. When this
  125. is done, SourceServer will give the message "Some files were checked out to the
  126. directory <project directory>".
  127.  
  128. Having files checked out to the root level will normally only occur with header
  129. files that you don't have local copies of. The TPM stores information about the
  130. location of files that are in the project (such as .c or .r files), but not of
  131. #included headers.
  132.  
  133.  
  134. SourceServer Timeouts:
  135.  
  136. The first release of the Think Project Manager would sometimes give a timeout
  137. error for SourceServer operations that took too long. One example was choosing
  138. the CheckOut... dialog for a remotely mounted project with a large number of
  139. files. 
  140.  
  141. The TPM will no longer time out SourceServer operations. You can cancel any
  142. command by pressing <command>-<period>. Note, however, that SourceServer will
  143. still need to finish a command in progress before a new command can be sent from
  144. the TPM.
  145.  
  146.  
  147. CheckIn Changes:
  148.  
  149. There has been a modification to the user interface of the file list in the
  150. CheckIn dialog. Double clicking on a file now does nothing (it used to Check In
  151. the file). This is to prevent checking a file in accidentally when you are just
  152. trying to browse a list of revisions.
  153.  
  154.  
  155. CheckOut Changes:
  156.  
  157. The default for file checkout has been changed from modify read-only to
  158. read-only.
  159.  
  160.  
  161. Using the Command Line Interface
  162. ________________________________
  163.  
  164. The Think Project Manager allows you to use the SourceServer Command Line
  165. interface. The commands and options are the same as MPW projector commands, 
  166. with the following exceptions:
  167.  
  168. - The commands MergeBranch and CompareRevisions are not available
  169. - Commands that have -w and -close options in MPW do not have corresponding
  170.   options in SourceServer.
  171.  
  172. To use the command line interface, enter a SourceServer command and all options,
  173. and press <ctrl> <enter> to send the line to SourceServer. Command lines can be sent
  174. this way from any window the Think Project Manager editor has open that is modifiable.
  175. Usually you will want to have a new untitled window available for sending commands.
  176.  
  177. Things to note about the command line options:
  178.  
  179. - When you need to specify a filename, use the Full Pathname
  180. - When using DeleteRevisions, be sure to specify the -y option
  181. - There is no help available, except for the usage summary, or through ToolServer
  182. - SourceServer commands are NOT case sensitive. Neither are file and 
  183.   folder names
  184. - When entering pathnames, if any file or folder has a space in the name,
  185.   the whole path name should be surrounded by double quotes
  186. - A file on the Desktop can be specified as "HD Name:Desktop Folder:filename"
  187.  
  188.  
  189. SourceServer Command Descriptions:
  190.  
  191. For all command descriptions and syntax listings, square brackets ( [] ) denote
  192. optional parameters. Parameters separated by the vertical bar ( | ) show mutually
  193. exclusive parameters. 
  194.  
  195.  
  196. CheckIn:   Checks a file or files into a projector database
  197.  
  198. Usage:  CheckIn [-p] [-u User] [-project Project] [-t task] [-new | -b] 
  199.         [-cs comment | -cf file] [-m | -delete] [-touch] [-verify]
  200.         [-y|-n|-c] (-a | file…)
  201.  
  202. Option summary:
  203.     -a                       Checkin all files in the current directory
  204.     -b                       Check in file… as branches
  205.     -c                       Cancel if conflict occurs (avoids dialog)
  206.     -cf file                 Look for comments in the file
  207.     -cs comment              Adds a description of changes made to the file
  208.     -delete                  Delete the file after checking it in
  209.     -m                       Checkout the files for modification after checking in
  210.     -n                       Answer no to all dialogs (avoids dialogs)
  211.     -new                     Add a new file to the project
  212.     -p                       Write progress information to standard output
  213.     -project project         Gives the name of project that contains the files
  214.     -t task                  Adds a short description of task accomplished
  215.     -touch                   Touch the mod date of file after checking in
  216.     -u user                  Gives the name of the current user
  217.     -verify                  Verify the contents of the checked in file
  218.     -y                       Answer yes to all dialogs (avoids dialogs)
  219.  
  220.  
  221.  
  222. CheckOut:   Checkout a file or files from a projector database
  223.  
  224. Usage: CheckOut [-p] [-m] [-b] [-cancel] [-u User] [-project Project] [-t task] 
  225.        [-d dir] [-cs comment | -cf file] [-r] [-open] [-y|-n|-c] [-noTouch|-touchOnly] 
  226.        [-history] [-verify] [-obsolete] (-update | -newer | -a | name*)
  227.  
  228. Option Summary:
  229.     -a                       Checkout all the files in the current project
  230.     -b                       Checkout specified files on a new branch
  231.     -c                       Cancel if conflict occurs (avoids dialog)
  232.     -cancel                  Cancel the checkout of the files
  233.     -cf file                 Looks for the comment in the file
  234.     -cs comment              Add a short description of changes
  235.     -d dir                   Names the Directory where the checked out files
  236.                              should go
  237.     -m                       Checkout a modifiable copy of the file
  238.     -n                       Answer no to all dialogs (avoids dialogs)
  239.     -newer                   Checkout latest copy of all files in the project
  240.     -noTouch                 Don't touch the mod date of the checked out files
  241.     -open                    Open the files after checking out
  242.     -p                       Write progress information to standard output
  243.     -project project         Name of project that contains the files
  244.     -r                       Recursively checkout files
  245.     -t task                  Add a short description of task accomplished
  246.     -u user                  Gives the name of current user
  247.     -update                  Checkout latest copy of all files you already have
  248.     -verify                  Verify the contents of the checked out file
  249.     -y                       Answer yes to all dialogs (avoids dialogs)
  250.     
  251. *name = file name | NameRevisions name
  252.  
  253.  
  254.  
  255. CheckOutDir:    Specify the directory where checked out files will be placed
  256.  
  257. Usage:  CheckOutDir [-project Project | -m] [-r] [-x | directory]
  258.  
  259. Option Summary:
  260.     -project project         Name the project to associate with the checkout directory    
  261.     -m                       List the checkout directories of all root projects
  262.     -r                       Recursively set or display the checkout directories
  263.     -x                       Reset the checkout directories to ":"
  264.  
  265.  
  266.  
  267. CompareRevisions:   Is not available with SourceServer
  268.  
  269.  
  270.  
  271. DeleteNames:   Delete user-defined symbolic names
  272.  
  273. Usage:   DeleteNames [-u User] [-project Project] [-public | -private] [-r] [names… | -a]
  274.  
  275. Option Summary:
  276.     -u user                  Name of current user
  277.     -private                 Delete private names
  278.     -project project         Name of project that contains the files
  279.     -public                  Delete public names (the default)
  280.     -r                       Delete names recursively
  281.     -a                       Delete all names
  282.  
  283.  
  284.  
  285. DeleteRevisions:   Delete previous revisions of files in a project
  286.  
  287. Usage:   DeleteRevisions [-u User] [-project Project] [-file] -y file…
  288.  
  289. Option Summary:
  290.     -u user                  Name the current user
  291.     -project project         Name the project that contains the files
  292.     -file                    Delete the file and all its revisions
  293.     -y                       Delete the file/revision. ALWAYS USE THIS OPTION
  294.                              OR SOURCESERVER WILL PUT UP A DIALOG BOX THAT
  295.                              YOU CANNOT RESPOND TO.
  296.  
  297.  
  298.  
  299. MergeBranch       MergeBranch is not available with SourceServer
  300.  
  301.  
  302.  
  303. ModifyReadOnly:   Enables read-only Projector files to be edited
  304.  
  305. Usage:   ModifyReadOnly file
  306.  
  307.  
  308.  
  309. MountProject     Mount projects
  310.  
  311. Usage:  MountProject ([-s] [-pp] [-q] [-r]) | [Project [-only] ]
  312.  
  313. Option Summary:
  314.     -s                       Print names only, not commands
  315.     -pp                      List mounted projects using project paths
  316.     -q                       Don't quote names with special characters
  317.     -r                       List projects recursively
  318.  
  319.  
  320.  
  321. NameRevisions    Define a symbolic name
  322.  
  323. Usage:   NameRevisions [-u User] [-project Project] [-public | -private | -b] [-r]
  324.         [[-only] | name [[-expand] [-s] | [-replace] [-dynamic] [names… | -a]]]
  325.         
  326. Option Summary:
  327.     -u user                  Name the current user
  328.     -private                 Create a private name
  329.     -project project         Name the project that contains the revisions
  330.     -public                  Create a public name (the default)
  331.     -b                       Print both public and private names
  332.     -expand                  Evaluate names to revision level before printing
  333.     -only                    Only print the names, not the associated revisions
  334.     -replace                 Completely overwrite the previous definition of name
  335.     -dynamic                 Evaluate names to revision level when using not defining
  336.     -r                       Recursively execute NameRevisions starting with current 
  337.                              project
  338.     -s                       Print a single name per line
  339.     -a                       All the files in the project
  340.  
  341.  
  342.  
  343. NewProject       Create a new project
  344.  
  345. Usage:  NewProject [-u User] [-cs comment | -cf file] project
  346.  
  347. Option Summary:
  348.     -cf file                 Look for the comments in file
  349.     -cs comment              Add a short description of the project
  350.     -u user                  Name the current user
  351.  
  352.  
  353.  
  354. OrphanFiles      Remove Projector info ('ckid' resource) from a list of files
  355.  
  356. Usage:    OrphanFiles file…
  357.  
  358.  
  359.  
  360. Project          Set or write the current project
  361.  
  362. Usage:   Project -q | [project]
  363.  
  364. Option Summary:
  365.     -q                       Don't quote projects with special characters
  366.  
  367.  
  368.  
  369. ProjectInfo      Display information about a Project
  370.  
  371. Usage:  ProjectInfo [-project Project] [-log] [-comments] [-latest] [-f] [-r] [-s] 
  372.         [-only | -m] [-af author | -a author] [-df dates | -d dates] 
  373.         [-cf pattern | -c pattern] [-t pattern] [-n name] [-update | -newer] [file…]
  374.  
  375. Option Summary:
  376.     -a author                Only list revisions created by author
  377.     -af author               Only list files created by author
  378.     -c pattern               Only list revisions whose comment contains pattern
  379.     -cf pattern              Only list files whose comment contains pattern
  380.     -comments                List comments along with the rest of the information
  381.     -d dates                 Only list revisions whose create date is within dates
  382.     -df dates                Only list files whose mod date is within dates
  383.     -f                       List file information
  384.     -log                     Print project log
  385.     -m                       Only list files/revisions that are checked out
  386.     -newer                   Gives info on files that would be checked out using
  387.                              this option     
  388.     -only                    Only list project information
  389.     -project project         Name the project to get information on
  390.     -r                       Recursively list subprojects
  391.     -latest                  Only list info on the latest revision on the main trunk
  392.     -s                       Use short listing, names and revision names only
  393.     -t pattern               Only list revisions whose task contains pattern
  394.     -n name                  Only list revisions that have name
  395.     -update                  Give info on files that would be checked out using
  396.                              this option     
  397.                              
  398.     Note: pattern is either a literal string or /regular expression/.
  399.     
  400.     Note: "dates" may take the following forms:
  401.         date                 On date
  402.         <date                Before but not including date
  403.         ≤date                Before and including date
  404.         >date                After and not including date
  405.         ≥date                After and including date
  406.         date-date            Between and including dates
  407.         
  408.     Note:  A date is mm/dd/yy [[hh:mm[:ss]] [AM|PM]]
  409.     
  410.     Note: "name" may take the following forms:
  411.         name                 In name
  412.         <name                Before name
  413.         ≤name                Before and including name
  414.         >name                After name
  415.         ≥name                After and including name
  416.  
  417.  
  418.  
  419. TransferCkid:   Move Projector information from one file to another
  420.  
  421. Usage:   TransferCkid fromFile toFile
  422.  
  423.  
  424.  
  425. UnmountProject   Unmount projects
  426.  
  427. Usage:  UnmountProject [-a | Project…]
  428.  
  429. Option Summary
  430.      -a                      Unmount all mounted projects
  431.